@jest/fake-timers

What is @jest/fake-timers?

@jest/fake-timers is a package that provides fake timer functions for Jest, a popular JavaScript testing framework. It allows you to control the passage of time in your tests, making it easier to test code that relies on timers, such as setTimeout, setInterval, and Date.

What are @jest/fake-timers's main functionalities?

Mocking setTimeout and setInterval

This feature allows you to mock setTimeout and setInterval functions, enabling you to control the passage of time in your tests. The code sample demonstrates how to use jest.useFakeTimers() to mock the timers and jest.advanceTimersByTime() to fast-forward time.

const { jest } = require('@jest/globals');

jest.useFakeTimers();

setTimeout(() => {
  console.log('This will be logged after 1 second');
}, 1000);

jest.advanceTimersByTime(1000); // Fast-forward time by 1 second

// Output: 'This will be logged after 1 second'

Mocking Date

This feature allows you to mock the Date object, enabling you to control the current date and time in your tests. The code sample demonstrates how to use jest.useFakeTimers('modern') to mock the Date object and jest.setSystemTime() to set a specific date and time.

const { jest } = require('@jest/globals');

jest.useFakeTimers('modern');

const now = Date.now();
console.log(now); // Outputs the current timestamp

jest.setSystemTime(new Date('2020-01-01'));

const newNow = Date.now();
console.log(newNow); // Outputs the timestamp for 2020-01-01

Clearing timers

This feature allows you to clear mocked timers, ensuring that the associated callbacks are not executed. The code sample demonstrates how to use clearTimeout() to clear a setTimeout timer.

const { jest } = require('@jest/globals');

jest.useFakeTimers();

const timeoutId = setTimeout(() => {
  console.log('This will not be logged');
}, 1000);

clearTimeout(timeoutId);

jest.advanceTimersByTime(1000); // Fast-forward time by 1 second

// No output

Other packages similar to @jest/fake-timers

sinon

Sinon is a popular standalone test spies, stubs, and mocks library for JavaScript. It provides similar functionalities to @jest/fake-timers, including the ability to mock timers and control the passage of time. However, Sinon is not tied to any specific testing framework and can be used with various testing libraries.

lolex

Lolex is a standalone library for creating fake timers and controlling the passage of time. It provides similar functionalities to @jest/fake-timers, such as mocking setTimeout, setInterval, and Date. Lolex can be used independently or integrated with other testing frameworks.

README

The README file is missing

Changelog

27.5.1

Features

• [jest-config] Support comments in JSON config file (#12316)
• [pretty-format] Expose ConvertAnsi plugin (#12308)

Fixes

• [expect] Add type definitions for asymmetric closeTo matcher (#12304)
• [jest-cli] Load binary via exported API (#12315)
• [jest-config] Replace jsonlint with parse-json (#12316)
• [jest-repl] Make module importable (#12311 & #12315)

Chore & Maintenance

• [*] Avoid anonymous default exports (#12313)